home *** CD-ROM | disk | FTP | other *** search
/ Experimental BBS Explossion 3 / Experimental BBS Explossion III.iso / c / sblib10.zip / SBLIB.DOC < prev    next >
Text File  |  1993-09-11  |  7KB  |  171 lines
  1.  SBLIB version 1.0
  2.  =================
  3.  
  4.  September 11, 1993
  5.  Written by Brian Clayton
  6.  HERZOGSoft Programming
  7.  
  8.      SBLIB is a small library of routines for playing .VOC Sound Blaster 
  9.  sound files in C.  The routines make use of the freely-distributable 
  10.  Sound Blaster driver CTVDSK.DRV.  The version of the CTVDSK.DRV driver 
  11.  included is the Sound Blaster Pro version, but it will work fine on normal 
  12.  Sound Blasters, too.  This driver can be legally distributed with any 
  13.  programs you write using the library.
  14.  
  15.      All of the routines in the library were written in pure assembler for 
  16.  simplicity and speed.  The routines use large memory model. 
  17.  
  18.  This library is freeware.  Feel free to do whatever you want with it.
  19.  
  20.  The library contains the following functions:
  21.      
  22.      loaddrv - loads driver CTVDSK.DRV from current directory
  23.      initdrv - initializes Sound Blaster, sets sound buffers
  24.      playvoc - plays an open .VOC file
  25.      stopvoc - stops a currently playing .VOC file
  26.      unloaddrv - de-initializes and terminates the driver
  27.      setbaseio - sets the base i/o address of sound card
  28.      setint - sets interrupt number for DMA
  29.  
  30.      NOTE:  Neither setbaseio nor setint has to be used.  The driver
  31.           assumes default values of 220h and 7, respectively, for each. 
  32.           If either is used, it must be called before initdrv. (See
  33.           description of each, further on.)
  34.  
  35.  For a complete sample program demonstrating the use of all the functions, 
  36.  see VOCPLAY.C.
  37.  
  38.  unsigned loaddrv( unsigned seg, unsigned size, char *fname )
  39.  ------------------------------------------------------------
  40.      This function loads the driver (CTVDSK.DRV) into the memory block
  41.      beginning at seg.  Use the _dos_alloc C function to allocate the memory
  42.      for the driver.  The loaddrv function returns 0 if successful, 1 if
  43.      unsuccessful.
  44.  
  45.      The first parameter (seg) is the segment address of the memory block to 
  46.      load the driver into.  This should be the segment address returned by 
  47.      the _dos_alloc function.
  48.  
  49.      The second parameter (size) is the number of bytes to load into the 
  50.      memory block specified by seg from the driver.  This value should always
  51.      be slightly larger than the size of the driver file in bytes.
  52.  
  53.      The last parameter (fname) is a string which contains the filename of
  54.      the driver file, including extension.  Unless you rename the driver 
  55.      file, this should be CTVDSK.DRV.
  56.  
  57.      Sample usage:
  58.           unsigned x, seg;
  59.           
  60.           _dos_allocmem( 8000 >> 4, &seg );
  61.           x = loaddrv( seg, 8000, "CTVDSK.DRV" );
  62.           
  63.  
  64.  unsigned initdrv( unsigned buf, unsigned *status )
  65.  --------------------------------------------------
  66.      This function initializes the Sound Blaster, using the driver, 
  67.      which must have been loaded already using loaddrv.  This function
  68.      returns 0 if succesful, 1 if unsuccessful.
  69.      
  70.      The first parameter (buf) is the number of 2k disk buffers for the 
  71.      driver to allocate.  This value can range from 1 to 32.  Lower values 
  72.      may make the sound choppier, but larger values use more memory.  If
  73.      you are unclear about what this parameter does, just try a value such
  74.      as 10.
  75.      
  76.      The last parameter (status) should be a far pointer to the status word.
  77.      The status word is the unsigned variable that will indicate the status
  78.      of the sound.  The driver will take care of updating this variable.
  79.      When sound is playing, it will contain a non-zero value.  When sound is
  80.      stopped, it should contain zero.  For some reason, however, in the 
  81.      times I tried, the driver did nothing to the variable, so the status 
  82.      word variable may not change like it is supposed to.  If you are not
  83.      sure about what this variable does, just pass a far pointer to an unused
  84.      unsigned variable.
  85.  
  86.      Sample usage:
  87.           unsigned status;
  88.  
  89.           initdrv( 10, &status );
  90.  
  91.  
  92.  unsigned playvoc( unsigned fhandle )
  93.  ------------------------------------
  94.      This function is used to play a .VOC file once the driver has been 
  95.      loaded and initialized using the two functions above.  In order to
  96.      use this function, you must first use the _dos_open function to open 
  97.      the .VOC file you wish to play.  This function returns 0 is successful.
  98.      
  99.      The fhandle parameter should contain the file handle of the open .VOC
  100.      file to play.  This should be the file handle returned by the _dos_open 
  101.      function.  When you close the file (using the _dos_close function) the 
  102.      music will stop, if it has not already.
  103.  
  104.      Sample usage:
  105.           unsigned handle;
  106.  
  107.           _dos_open( "test.voc", 0, &handle );
  108.           playvoc( handle );
  109.  
  110.  
  111.  void stopvoc( )
  112.  ---------------
  113.      This function stops any currently playing .VOC file.
  114.  
  115.      Sample usage:
  116.           stopvoc( );
  117.  
  118.  
  119.  void unloaddrv( )
  120.  -----------------
  121.      This function simply terminates the driver, it does not free up the
  122.      memory you allocated for it.  You must free the allocated memory using 
  123.      the _dos_freemem function.
  124.  
  125.      Sample usage:
  126.           unloaddrv( );
  127.      
  128.  
  129.  void setbaseio( unsigned address )
  130.  ----------------------------------
  131.      This function sets the base i/o address in the driver that the Sound
  132.      Blaster uses.  If this function is not called, the driver assumes the 
  133.      default, 220h (hex).
  134.      NOTE:  This function, if used at all, must be called before using 
  135.           initdrv.
  136.  
  137.      The address parameter is the base i/o address for the Sound Blaster.
  138.      For the Sound Blaster Pro, this can be either 220h or 240h.  The
  139.      normal Sound Blaster has six possible i/o addresses:  210h, 220h, 230h,
  140.      240h, 250h, and 260h.
  141.  
  142.      Sample usage:
  143.           setbaseio( 0x220 );
  144.  
  145.  
  146.  void setint( unsigned intr )     
  147.  ----------------------------
  148.      This function sets the DMA interrupt number of the Sound Blaster.  If
  149.      this function is not called, the driver uses the default value of 7.
  150.      NOTE:  This function, if used at all, must be called before using 
  151.           initdrv.
  152.  
  153.      The intr parameter is the interrupt number for the DMA.  The Sound 
  154.      Blaster Pro has four possible DMA interrupts: 2, 5, 7, and 10.  The
  155.      normal Sound Blaster has four possible DMA interrupts: 2, 3, 5, and 7.
  156.  
  157.      Sample usage:
  158.           setint( 7 );
  159.  
  160.  ----------------------------------------------------------------------------
  161.  This library was written and tested on a 40Mhz 386DX with a Sound Blaster
  162.  Pro 2.  This library is freeware.
  163.  
  164.  ----------------------------------------------------------------------------
  165.  Feel free to send any questions, comments or suggestions to:
  166.      
  167.      Brian Clayton
  168.      6 Granada Terrace
  169.      Middletown, RI
  170.      02842
  171.